home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / php / pear / docs / PhpDocumentor / FAQ < prev    next >
Text File  |  2004-03-24  |  7KB  |  177 lines
  1. ################################################################################
  2.                 phpDocumentor Frequently Asked Questions
  3.  
  4. ################################################################################
  5. Introduction
  6. ################################################################################
  7.  
  8. Before we start with questions and their answers, make sure to read the
  9. documentation *thoroughly* found at http://www.phpdoc.org/manual.php.  The
  10. complexity of phpDocumentor can be a bit impenetrable until you understand the
  11. logic behind it.
  12.  
  13. If you have read the documentation thoroughly, and have read this FAQ and you
  14. are still lost, please go directly to the bug database at
  15. http://sourceforge.net/tracker/?group_id=11194&atid=111194 and read through the
  16. open bugs.  If you don't find the solution to your problem (or proof that it
  17. at least is not your fault), then go to the help forum and post a help message
  18. at http://sourceforge.net/forum/forum.php?forum_id=35065.
  19.  
  20. ################################################################################
  21. All Questions (Table of Contents)
  22. ################################################################################
  23. Installation
  24.  Q: [UNIX ONLY] When I run phpdoc from outside its directory, it doesn't work!
  25.  Q: [PEAR ONLY] I ran pear install PhpDocumentor, but running 'phpdoc' doesn't
  26.     work!
  27. Documentation Errors
  28.  Q: I keep getting an illegal package tag error for the first DocBlock in a file,
  29.     isn't this a page-level DocBlock?
  30.  Q: I keep getting a warning that there is no @package tag in file xxx.php, but
  31.     there is a @package tag in the class definition, doesn't this apply to the
  32.     file?
  33. Feature Requests
  34.  Q: Can you implement the @example tag inline so that I can put PHP source code
  35.     examples directly in DocBlocks?
  36. Crash/Segfaults
  37.  Q: phpDocumentor crashes if I use __FUNCTION__!!!
  38.  
  39. ################################################################################
  40. Installation
  41. ################################################################################
  42.  
  43. All old FAQ's for installation have been fixed in version 1.2.2, please open a
  44. bug if you continue to have these problems
  45.  
  46. ################################################################################
  47. Documentation Errors
  48. ################################################################################
  49.  
  50. Q: I keep getting an illegal package tag error for the first DocBlock in a file,
  51.    isn't this a page-level DocBlock?
  52.  
  53. ---
  54. ---[[UPDATE]]
  55. ---VERSION 1.2.2 has a different page-level docblock recognition algorithm
  56. ---Now, the first docblock in a file is a page-level docblock if it contains
  57. ---a @package tag.
  58. ---
  59. A: Please read the documentation very carefully.  A page-level DocBlock does
  60.    occur at the start of a file, but the first DocBlock is not always a
  61.    page-level DocBlock!  Why is this?  Very often, you will want to document
  62.    the entire page, or describe it (this page contains functions for blah), and
  63.    also document the first item in a page separately.  An example:
  64.    
  65.    <?php
  66.    /**
  67.    * This file contains all foobar functions and defines
  68.    * @package mypackage
  69.    */
  70.    /**
  71.    * controls parsing of bar information
  72.    */
  73.    define('parse_bar',true);
  74.    ?>
  75.    
  76.    The page has its own information, and the define has its own information.
  77.    An example of what not to do:
  78.    
  79.    <?php
  80.    /**
  81.    * This file contains all foobar functions and defines
  82.    * @package mypackage
  83.    */
  84.    define('parse_bar',true);
  85.    ?>
  86.    
  87.    Here, the DocBlock belongs to the define and not to the page!  phpDocumentor
  88.    can successfully parse this DocBlock, but it will apply the comment to the
  89.    documentation of define('parse_bar',true); and not to the page.  Therefore,
  90.    it warns you that your @package tag will be ignored because defines may not
  91.    contain a @package tag.
  92.  
  93. Q: I keep getting a warning that there is no @package tag in file xxx.php, but
  94.    there is a @package tag in the class definition, doesn't this apply to the
  95.    file?
  96.  
  97. A: No.  this example does not have a page-level DocBlock:
  98.  
  99.    <?php
  100.    /**
  101.    * This class is in package mypackage
  102.    * @package mypackage
  103.    */
  104.    class in_mypackage {...}
  105.    ?>
  106.    
  107.    phpDocumentor therefore assumes the page-level package is the same as the
  108.    class package, mypackage.  This is fine in most cases, but if multiple
  109.    classes are in the same file with different packages, as in:
  110.  
  111.    <?php
  112.    /**
  113.    * This class is in package mypackage
  114.    * @package mypackage
  115.    */
  116.    class in_mypackage {...}
  117.    /**
  118.    * This class is in package anotherpackage
  119.    * @package anotherpackage
  120.    */
  121.    class in_anotherpackage {...}
  122.    ?>
  123.    
  124.    There is no way to determine which package the page should belong to, and
  125.    phpDocumentor will automatically put it in the default package.  This can
  126.    cause incredible headaches debugging, and so we have added a warning in the
  127.    1.2.0 series that informs you if the package is inferred by phpDocumentor.
  128.    To fix this warning, simply place a page-level DocBlock with a @package tag
  129.    like:
  130.  
  131.    <?php
  132.    /**
  133.    * This file contains two packages
  134.    * @package filepackage
  135.    */
  136.    /**
  137.    * This class is in package mypackage
  138.    * @package mypackage
  139.    */
  140.    class in_mypackage {...}
  141.    /**
  142.    * This class is in package anotherpackage
  143.    * @package anotherpackage
  144.    */
  145.    class in_anotherpackage {...}
  146.    ?>
  147. ################################################################################
  148. Feature Requests
  149. ################################################################################
  150. Q: Can you implement the @example tag inline so that I can put PHP source code
  151.    examples directly in DocBlocks?
  152.  
  153. A: This is implemented using the HTML <code></code> tags as in:
  154.  
  155.    /**
  156.     * Short description
  157.     *
  158.     * Start of long description, here is a code example:
  159.     * <code>
  160.     *  $my_phpcode = "easy to explain";
  161.     * </code>
  162.     * More text
  163.     * <code>
  164.     *  define('morecode',true);
  165.     * </code>
  166.     */
  167. ################################################################################
  168. Crash/Segfaults
  169. ################################################################################
  170. Q: phpDocumentor crashes if I use __FUNCTION__!!!
  171.  
  172. A: This is caused by a known bug in all PHP versions prior to 4.3.2.  It was
  173.    fixed in PHP 4.3.2RC1, you must upgrade to PHP 4.3.2 if you use __FUNCTION__
  174.    in code that you wish to document (sorry!) or apply the bugfix patch to the
  175.    tokenizer extension and recompile php (see the php.internals archive at
  176.    php.net for help)
  177.